array.prototype.flatmap

What is array.prototype.flatmap?

The array.prototype.flatmap package provides a polyfill for the flatMap method that was added to the Array prototype in ECMAScript 2019. This method allows you to map over an array and flatten the result by one level in a single operation. It is particularly useful for dealing with arrays of arrays or when applying a function that returns an array for each element.

What are array.prototype.flatmap's main functionalities?

Mapping and Flattening

This code demonstrates how to use flatMap to map over an array of arrays, doubling each element, and then flattening the result into a single array. The output would be [2, 4, 6, 8].

[[1, 2], [3, 4]].flatMap(x => x.map(y => y * 2))

Filtering and Mapping in One Step

This example shows how flatMap can be used to filter and map over an array simultaneously. It doubles the even numbers and removes the odd numbers, resulting in [4, 8].

[1, 2, 3, 4].flatMap(x => x % 2 === 0 ? [x * 2] : [])

Other packages similar to array.prototype.flatmap

lodash.flatten

Lodash's flatten method provides similar functionality to flatMap for flattening arrays, but it does not include mapping. You would need to chain it with map for similar effects, making array.prototype.flatmap more convenient for combined operations.

underscore.js

Underscore.js offers methods like _.flatten and _.map which can be combined to achieve similar results to flatMap. However, like lodash, this requires chaining multiple operations, whereas array.prototype.flatmap integrates both into one method.

README

array.prototype.flatmap

An ES2019 spec-compliant Array.prototype.flatMap shim/polyfill/replacement that works as far down as ES3.

This package implements the es-shim API interface. It works in an ES3-supported environment and complies with the spec.

Because Array.prototype.flatMap depends on a receiver (the this value), the main export takes the array to operate on as the first argument.

Getting started

npm install --save array.prototype.flatmap

Usage/Examples

var flatMap = require('array.prototype.flatmap');
var assert = require('assert');

var arr = [1, [2], [], 3];

var results = flatMap(arr, function (x, i) {
	assert.equal(x, arr[i]);
	return x;
});

assert.deepEqual(results, [1, 2, 3]);

var flatMap = require('array.prototype.flatmap');
var assert = require('assert');
/* when Array#flatMap is not present */
delete Array.prototype.flatMap;
var shimmedFlatMap = flatMap.shim();

var mapper = function (x) { return [x, 1]; };

assert.equal(shimmedFlatMap, flatMap.getPolyfill());
assert.deepEqual(arr.flatMap(mapper), flatMap(arr, mapper));

var flatMap = require('array.prototype.flatmap');
var assert = require('assert');
/* when Array#flatMap is present */
var shimmedIncludes = flatMap.shim();

var mapper = function (x) { return [x, 1]; };

assert.equal(shimmedIncludes, Array.prototype.flatMap);
assert.deepEqual(arr.flatMap(mapper), flatMap(arr, mapper));

Tests

Simply clone the repo, npm install, and run npm test

Changelog

v1.3.3 - 2024-12-15

Commits

• [actions] split out node 10-20, and 20+ 8727281
• [Tests] add test coverage 6e78327
• [Deps] update call-bind, es-abstract e027dd1
• [Dev Deps] update @es-shims/api, @ljharb/eslint-config, auto-changelog, object-inspect, tape 7322d84
• [Dev Deps] update aud, npmignore, object-inspect, tape 958bf5c
• [Deps] update call-bind, define-properties, es-abstract, es-shim-unscopables b3698fb
• [Tests] replace aud with npm audit e0461ed
• [Dev Deps] add missing peer dep e7160b5